I love the way this looks! Thanks so much for working on this.

@zarr-developers/python-core-devs it would be good to get some feedback on this. Switching our docs is a big decision, and it only makes sense to put effort in this if everyone is aligned. I personally think we should 100% move to mkdocs-material, but it would be good to hear if there are any big objections to that.

Aesthetically, and in terms of user-friendliness, I think this PR represents a huge improvement. If we just consider the landing page, this:

is vastly better than this:

Apologies, I thought I had 👍'd previously. Now doing that retroactively in a general sense of the move and specifically for the style & the use of markdown.

But I agree that we need a careful review of the pages (and personally, I liked the cards on the landing page)

Thanks a lot for working on this, @maxrjones!
Looks great!

I love the switch from .rst to .markdown—it makes it easy to update and lowers the barrier for contribution.

I liked the cards on the landing page

I'm with Josh on this one. Can we also add cards in mk-docs?

i am actually strongly anti-cards, because they take up a huge amount of space that could be devoted to actual content.

Here's how much space the "user guide" link consumes in the mkdocs version in this PR:

Compare with the space used in our current version for the same information:

...and why do we need text on this card that explains what a user guide is? Isn't it evident that a user guide is a guide for users?

Similarly, if we take the "quick start" card, IMO the first thing people see when they come to the docs should be the "quick start" content. We shouldn't ask people to click on a link after coming to our docs to see how to use zarr. In max's PR, he puts that content front-and-center on the main page:

by contrast, the old docs waste a huge amount of space with the card, which also has a very confusing "person escaping from an industrial accident" icon:

So yeah, in summary part of what makes this PR great to me is the removal of the cards. They are dead weight from a UX POV.